home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / c / gymake12.zip / MAKE.DOC < prev    next >
Text File  |  1988-11-18  |  16KB  |  390 lines
  1. NAME
  2.      make - maintain, update, and reconstruct groups of programs
  3.  
  4. SYNOPSIS
  5.      make [-f makefile] [-dDeinrst] [target...] [macro=value ...]
  6.  
  7. DESCRIPTION
  8.      MAKE takes a file of dependencies (a 'makefile') and decides what
  9.      commands have to be executed to bring the files up to date.  These
  10.      commands are either executed directly from MAKE or written to the
  11.      standard output without executing them.
  12.  
  13.      If no makefile is specified with a -f option, MAKE reads a file
  14.      named `makefile', if it exists.
  15.  
  16.      If no target is specified on the command line, MAKE uses the first
  17.      target defined in the first makefile.
  18.  
  19. OPTIONS
  20.      -f makefile
  21.          Use the description file `makefile'.  A - as the makefile
  22.          argument denotes the standard input.
  23.  
  24.      -d  Display the reasons why MAKE chooses to rebuild a target.  All
  25.          dependencies which are newer are displayed
  26.  
  27.      -dd Display the dependency checks in more detail.  Dependencies
  28.          which are older are displayed, as well as newer.
  29.  
  30.      -D  Display the text of the makefiles as read in.
  31.  
  32.      -DD Display the text of the makefiles and `default.mk'.
  33.  
  34.      -e  Let environment variables override macro definitions from
  35.          makefiles.  Normally, makefile macros override environment
  36.          variables.  Command line macro definitions always override both
  37.          environment variables and makefile macros definitions.
  38.  
  39.      -i  Ignore error codes returned by commands.  This is equivalent to
  40.          the special target .IGNORE:.
  41.  
  42.      -n  No execution mode.  Print commands, but do not execute them.
  43.          Even lines beginning with an @ are printed.  However, if a
  44.          command line is an invocation of MAKE, that line is always
  45.          executed.
  46.  
  47.      -r  Do not read in the default file `default.mk'.
  48.  
  49.      -s  Silent mode.  Do not print command lines before executing them.
  50.          This is equivalent to the special target .SILENT:.
  51.  
  52.      -t  Touch the target files, bringing them up to date, rather than
  53.          performing the rules to reconstruct them.
  54.  
  55.      macro=value
  56.          Macro definition.  This definition remains fixed for the MAKE
  57.          invocation.  It overrides any regular definitions for the
  58.          specified macro within the makefiles and from the environment.
  59.          It is inherited by subordinate MAKE's but act as an environment
  60.          variable for these.  That is, depending on the -e setting, it
  61.          may be overridden by a makefile definition.
  62.  
  63. USAGE
  64.   Makefiles
  65.      The first makefile read is `default.mk', which can be located any-
  66.      where along the PATH.  It typically contains predefined macros and
  67.      implicit rules.
  68.  
  69.      The default name of the makefile is `makefile' in the current
  70.      directory.  An alternate makefile can be specified using one or
  71.      more '-f' options on the command line.  Multiple '-f's act as the
  72.      concatenation of all the makefiles in a left-to-right order.
  73.  
  74.      The makefile(s) may contain a mixture of comment lines, macro
  75.      definitions, include lines, and target lines.  Lines may be
  76.      continued across input lines by escaping the NEWLINE with a
  77.      backslash (\).
  78.  
  79.      Anything after a "#" is considered to be a comment, and is stripped
  80.      from the line.  Completely blank lines are ignored.
  81.  
  82.      An include line is used to include the text of another makefile.
  83.      It consists of the word "include" left justified, followed by
  84.      spaces, and followed by the name of the file that is to be included
  85.      at this line.  Include files may be nested.
  86.  
  87.   Macros
  88.      Macros have the form `WORD = text and more text'.  The WORD need
  89.      not be uppercase, but this is an accepted standard.  Later lines
  90.      which contain $(WORD) or ${WORD} will have this replaced by `text
  91.      and more text'.  If the macro name is a single character, the
  92.      parentheses are optional.  Note that the expansion is done
  93.      recursively, so the body of a macro may contain other macro
  94.      invocations.
  95.  
  96.     e.g.    FLINTSTONES = wilma and fred
  97.         RUBBLES = barney and betty
  98.         BEDROCK = $(FLINTSTONES) and $(RUBBLES)
  99.  
  100.      `$(BEDROCK)' becomes `wilma and fred and barney and betty'
  101.  
  102.      Also note that whitespace around the equal sign is not relevant
  103.      when defining a macro.  The following four macro definitions are
  104.      all equivalent:
  105.  
  106.         MACRO = body
  107.         MACRO=  body
  108.         MACRO  =body
  109.         MACRO=body
  110.  
  111.      Macros may be added to by using the `+=' notation.  Thus
  112.  
  113.         FLINTSTONES += pebbles and dino
  114.  
  115.      would be (given the examples above) the same as
  116.  
  117.         FLINTSTONES = wilma and fred and pebbles and dino
  118.  
  119.   Special Macros
  120.      MAKE
  121.          This normally has the value "make".  Any line which invokes
  122.          MAKE temporarily overrides the -n option, just for the duration
  123.          of the one line.  This allows nested invocations of MAKE to be
  124.          tested with the -n option.
  125.  
  126.      MAKEFLAGS
  127.          This macro has the set of options provided to MAKE as its
  128.          value.  If this is set as an environment variable, the set of
  129.          options is processed before any command line options.  This
  130.          macro may be explicitly passed to nested MAKEs, but it is also
  131.          available to these invocations as an environment variable.
  132.  
  133.      SUFFIXES
  134.          This contains the default list of suffixes supplied to the
  135.          special target .SUFFIXES:.  It is not sufficient to simply
  136.          change this macro in order to change the .SUFFIXES: list.  That
  137.          target must be specified in your makefile.
  138.  
  139.      There are several dynamically maintained macros that are useful as
  140.      abbreviations within rules.  It is best not to define them
  141.      explicitly.
  142.  
  143.      $*  The basename of the current target.
  144.  
  145.      $<  The name of the current dependency file.
  146.  
  147.      $@  The name of the current target.
  148.  
  149.      The $< and $* macros are normally used for implicit rules.  They
  150.      may be unreliable when used within explicit target command lines.
  151.  
  152.   Targets
  153.      A target entry in the makefile has the following format:
  154.  
  155.     target ... : [dependency ...]
  156.         [rule]
  157.         ...
  158.  
  159.      Any line which does not have leading whitespace (other than macro
  160.      definitions) is a `target' line.  Target lines consist of one or
  161.      more filenames (or macros which expand into same) called targets,
  162.      followed by a semi-colon (:).  The ':' is followed by a list of
  163.      dependent files.
  164.  
  165.      Special allowance is made on MSDOS for the colons which are needed
  166.      to specify files on other drives, so for example, the following
  167.      will work as intended:
  168.  
  169.         c:foo.bar : a:fee.ber
  170.  
  171.      If a target is named in more than one target line, the dependencies
  172.      and rules are added to form the target's complete dependency list
  173.      and rule list.
  174.  
  175.      The dependents are ones from which a target is constructed.  They
  176.      in turn may be targets of other dependents.  In general, for a
  177.      particular target file, each of its dependent files is `made', to
  178.      make sure that each is up to date with respect to it's dependents.
  179.  
  180.      The modification time of the target is compared to the modification
  181.      times of each dependent file.  If the target is older, one or more
  182.      of the dependents have changed, so the target must be constructed.
  183.      Of course, this checking is done recursively, so that all
  184.      dependents of dependents of dependents of ...  are up to date.
  185.  
  186.      To reconstruct a target, MAKE expands macros, strips off initial
  187.      whitespace, and either executes the rules directly, or passes each
  188.      to a shell or COMMAND.COM for execution.
  189.  
  190.      For target lines, macros are expanded on input.  All other lines
  191.      have macro expansion delayed until absolutely required.
  192.  
  193.   Special Targets
  194.      .DEFAULT:
  195.          The rule for this target is used to process a target when there
  196.          is no other entry for it, and no implicit rule for building it.
  197.          MAKE ignores all dependencies for this target.
  198.  
  199.      .DONE:
  200.          This target and its dependencies are processed